Castle Model Converter (formerly tovrmlx3d)

Table of Contents

1. Introduction
2. Download
3. Basic Usage
4. Examples
5. All Command-line Options
- 5.1. Deprecated

1. Introduction

castle-model-converter is a command-line converter for various 3D and 2D model formats supported by Castle Game Engine.

As input, supports all 3D and 2D model formats supported by Castle Game Engine: glTF, X3D, VRML, Spine JSON, sprite sheets (in Castle Game Engine, Cocos2D and Starling XML formats), MD3, Wavefront OBJ, 3DS, STL, Collada, and more.

As output, we support X3D, VRML and STL. You can convert any input format to X3D or STL. You can also convert between X3D classic and X3D XML encodings (in both directions) and you can convert (upgrade) from VRML 2.0 to X3D.

Note	We plan to add soon glTF output (from any input).

We can also validate the input model, without doing any conversion.

2. Download

Simply download Castle Model Viewer. The downloaded package contains also castle-model-converter binary.

The Castle Model Viewer GUI application can also be used to do the conversion. Just use "File → Save As …" menu items. So you don’t need to use the command-line tool if you prefer GUI.

You can also use our online version of the converter if you don’t want to install anything :)

3. Basic Usage

Call with these parameters:

The input filename. It can be any filename, URL or - (to mean standard input).

Required.
The output filename. It can be any filename, URL or - (to mean standard output).

This parameter is optional. If not provided, the output is written to the standard output (so it is equivalent to using - as the output filename), unless --validate is used (then the output is not written anywhere).

4. Examples

# Convert glTF to X3D
castle-model-converter input.gltf output.x3d

# Validate some glTF and X3D files
castle-model-converter --validate input.gltf
castle-model-converter --validate input.x3d

# Convert file from X3D classic encoding to X3D XML encoding
castle-model-converter input.x3dv output.x3d

# Convert file from X3D XML encoding to X3D classic encoding
castle-model-converter input.x3d output.x3dv

# Convert VRML 2.0 to X3D in classic encoding.
castle-model-converter input.wrl output.x3dv

# Convert standard input to standard output
castle-model-converter - - < input.x3dv > output.x3dv
castle-model-converter - --stdin-url=fakeurl.gltf - < input.gltf > output.x3dv

5. All Command-line Options

--validate

Only validate the input model, don’t do any conversion. Will exit with non-zero status if the input is not 100% valid. Even warnings (that are ignorable during normal conversion) cause non-zero exit status when validating.

Note

Our "validation" isn’t 100% complete, that is: passing the validation doesn’t guarantee that your model satisfies every detail of the specification of given format. We check for a lot of model issues (including, but not limited to, issues that would make it impossible to render this model using Castle Game Engine). But it’s not a complete validation of the model per every detail of the specification.

--no-x3d-extensions

Do not use Castle Game Engine extensions. This will output file valid in all X3D browsers (but maybe with some Castle Game Engine-specific features missing).

--enable-downloads

Enable (blocking) downloads from the net, e.g. to download a texture or inlined (using X3D Inline node) models referenced by htt(s) protocol.

--stdin-url=URL

If input URL is -, then we read file contents from the standard input. In this case, you can use this option to provide a fake URL for the input. We will use it to resolve relative URLs inside the input (e.g. to glTF binary blobs, textures or X3D inlines) and to determine the input file type. Default is stdin.x3dv in current directory, so we assume input is X3D (classic encoding), and resolve URLs with respect to the current directory.

--stdout-url=URL

If output URL is -, then we write file contents to the standard output. In this case, you can use this option to provide a fake URL for the output. We will use it to determine the output file type. Default is stdout.x3dv in current directory, so we make output in X3D (classic encoding).

--float-precision=DIGITS

Number of digits after the decimal point when writing floating-point numbers. Default is to write all possibly relevant digits. Specify any value >= 0 to use this number of digits.

-h / --help

Print the help message and exit.

-v / --version

Print the version number and exit.

5.1. Deprecated

--encoding=classic|xml: Deprecated. Use given X3D encoding on output. By default, we use classic encoding (suitable for X3D files with .x3dv extensions).

Deprecated, do not use this. The 2nd parameter should determine the output type, ".x3d" extension says to make X3D XML, ".x3dv" says to make X3D classic. Or use --stdout-url to provide fake URL in case output is to stdout.

To improve this documentation just edit this page and create a pull request to cge-www repository.